#pragma once

#include "cpo.h"
#include "traits.h"

#include <stlcompat/span.h>

#include <array>
#ifndef SERIALIZER_HAS_STD_BIT
#if defined(__cpp_lib_endian) && (__cpp_lib_endian >= 201907L)
#include <bit>
#define SERIALIZER_HAS_STD_BIT 1
#else
#define SERIALIZER_HAS_STD_BIT 0
#endif
#endif
#include <bitset>
#include <charconv>
#include <chrono>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <forward_list>
#include <limits>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <tuple>
#include <type_traits>
#include <unordered_set>
#include <valarray>
#include <variant>
#include <vector>

namespace serializer
{

// ============================================================================
// 字节序处理工具
// ============================================================================

enum class byte_order : int
{
    little_endian = 0,
    big_endian = 1,
    native = 2
};

constexpr byte_order
native_byte_order() noexcept
{
#if SERIALIZER_HAS_STD_BIT
    if constexpr (std::endian::native == std::endian::little)
    {
        return byte_order::little_endian;
    }
    else
    {
        return byte_order::big_endian;
    }
#else
#if defined(SERIALIZER_NATIVE_ENDIAN_LITTLE)
    return byte_order::little_endian;
#elif defined(SERIALIZER_NATIVE_ENDIAN_BIG)
    return byte_order::big_endian;
#else
    return byte_order::little_endian; // 默认安全回退：小端
#endif
#endif
}

/**
 * 按目标字节序转换“可移植算术类型”的字节序（整数以及受支持的 IEEE754 浮点：float/double）。
 * 参数:
 *  - value: 待转换的值（整数或 float/double）
 *  - target_order: 目标字节序（little_endian/big_endian/native）
 * 返回值:
 *  - 按目标字节序转换后的值
 * 异常:
 *  - 无（noexcept）。当 T 为 long double
 * 等不受支持的浮点类型时，默认序列化路径不会调用本函数（因概念约束），需用户自定义。 说明:
 *  - 整数类型使用 std::byteswap 进行字节序转换；
 *  - 浮点类型在确认为 IEEE754 且尺寸为 4/8 字节（float/double）时，按字节反转；
 *  - 对于 sizeof(T)==1 的类型，字节序无意义，直接返回。
 */
template <typename T,
          typename std::enable_if<serializer::portable_arithmetic_type<T>, int>::type = 0>
constexpr T
convert_byte_order(T value, byte_order target_order) noexcept
{
    if (target_order == byte_order::native || target_order == native_byte_order())
    {
        return value;
    }

    if constexpr (sizeof(T) == 1)
    {
        return value;
    }
    else
    {
        if constexpr (std::is_integral<T>::value)
        {
#if defined(__cpp_lib_byteswap) && (__cpp_lib_byteswap >= 202110L)
            return std::byteswap(value);
#else
            using U = std::make_unsigned_t<T>;
            U u = static_cast<U>(value);
            if constexpr (sizeof(U) == 2)
            {
                u = static_cast<U>(__builtin_bswap16(static_cast<std::uint16_t>(u)));
            }
            else if constexpr (sizeof(U) == 4)
            {
                u = static_cast<U>(__builtin_bswap32(static_cast<std::uint32_t>(u)));
            }
            else if constexpr (sizeof(U) == 8)
            {
                u = static_cast<U>(__builtin_bswap64(static_cast<std::uint64_t>(u)));
            }
            return static_cast<T>(u);
#endif
        }
        else
        {
            T result{};
            auto * src_bytes = reinterpret_cast<const std::byte *>(&value);
            auto * dst_bytes = reinterpret_cast<std::byte *>(&result);
            for (std::size_t i = 0; i < sizeof(T); ++i)
            {
                dst_bytes[i] = src_bytes[sizeof(T) - 1 - i];
            }
            return result;
        }
    }
}

// ============================================================================
// 基础序列化选项实现
// ============================================================================

struct default_options
{
    /**
     * 获取字节序设置
     * 返回值: 字节序枚举值（serializer::byte_order）
     * 异常: 无
     */
    constexpr byte_order get_byte_order() const noexcept { return byte_order_; }

    /**
     * 获取最大容器大小限制
     * 返回值: 最大容器大小
     * 异常: 无
     */
    constexpr std::size_t max_container_size() const noexcept { return max_container_size_; }

    /**
     * 获取最大字符串长度限制
     * 返回值: 最大字符串长度
     * 异常: 无
     */
    constexpr std::size_t max_string_length() const noexcept { return max_string_length_; }

    /**
     * 获取最大递归深度限制
     * 返回值: 最大递归深度
     * 异常: 无
     */
    constexpr std::size_t max_recursion_depth() const noexcept { return max_recursion_depth_; }

    /**
     * 是否启用变长（uLEB128）长度字段编码
     * 返回值: true 表示启用, false 表示禁用
     * 异常: 无
     */
    constexpr bool enable_varint_lengths() const noexcept { return enable_varint_lengths_; }

    /**
     * 设置字节序
     * 参数: order 字节序
     * 返回值: 新的选项对象
     * 异常: 无
     */
    constexpr default_options with_byte_order(byte_order order) const noexcept
    {
        default_options result = *this;
        result.byte_order_ = order;
        return result;
    }

    /**
     * 设置最大容器大小限制
     * 参数: size 最大容器大小
     * 返回值: 新的选项对象
     * 异常: 无
     */
    constexpr default_options with_max_container_size(std::size_t size) const noexcept
    {
        auto result = *this;
        result.max_container_size_ = size;
        return result;
    }

    /**
     * 设置最大字符串长度限制
     * 参数: length 最大字符串长度
     * 返回值: 新的选项对象
     * 异常: 无
     */
    constexpr default_options with_max_string_length(std::size_t length) const noexcept
    {
        auto result = *this;
        result.max_string_length_ = length;
        return result;
    }

    /**
     * 设置最大递归深度限制
     * 参数: depth 最大递归深度
     * 返回值: 新的选项对象
     * 异常: 无
     */
    constexpr default_options with_max_recursion_depth(std::size_t depth) const noexcept
    {
        auto result = *this;
        result.max_recursion_depth_ = depth;
        return result;
    }

    /**
     * 启用/禁用变长长度字段编码
     * 参数: enabled 是否启用
     * 返回值: 新的选项对象
     * 异常: 无
     */
    constexpr default_options with_varint_lengths(bool enabled) const noexcept
    {
        auto result = *this;
        result.enable_varint_lengths_ = enabled;
        return result;
    }

    /**
     * 查询是否以十进制文本编码方式序列化 long double（用于跨平台可移植）。
     * 返回值: true 表示启用十进制文本编码；false 表示禁用（默认）。
     * 异常: 无
     * 说明: 当禁用时，库对 long double 默认不提供序列化支持，调用将抛出异常；
     *       当启用时，long double 将以十进制字符串编码，前缀写入长度。
     */
    constexpr bool prefer_decimal_for_long_double() const noexcept
    {
        return prefer_decimal_for_long_double_;
    }

    /**
     * 配置是否启用 long double 的十进制文本编码序列化。
     * 参数: enabled 是否启用
     * 返回值: 新的选项对象
     * 异常: 无
     */
    constexpr default_options with_prefer_decimal_for_long_double(bool enabled) const noexcept
    {
        auto result = *this;
        result.prefer_decimal_for_long_double_ = enabled;
        return result;
    }

private:
    serializer::byte_order byte_order_ = serializer::byte_order::little_endian;
    std::size_t max_container_size_ = 1'000'000;
    std::size_t max_string_length_ = 1'000'000;
    std::size_t max_recursion_depth_ = 100;
    bool enable_varint_lengths_ = false;
    bool prefer_decimal_for_long_double_ = false;
};

// ============================================================================
// 默认上下文实现与递归深度守卫
// ============================================================================

/**
 * 默认的序列化上下文实现
 * - 追踪当前递归深度并与最大允许深度对比
 * - 可选择性地追踪引用关系以检测简单环
 * - 统计对象处理数量（轻量示意，不在所有路径精确计数字节）
 */
class DefaultContext
{
public:
    /**
     * 构造默认上下文
     * 参数: max_depth 最大递归深度
     * 返回值: 无
     * 异常: 无
     */
    explicit DefaultContext(std::size_t max_depth) noexcept
        : _current_depth(0), _max_depth(max_depth), _bytes_processed(0), _objects_processed(0)
    {
    }

    /** 获取当前递归深度 */
    std::size_t current_depth() const noexcept { return _current_depth; }

    /** 递归深度加一；若超过最大深度将抛出异常 */
    void increment_depth()
    {
        ++_current_depth;
        if (!check_depth_limit())
        {
            throw std::runtime_error("Recursion depth exceeded maximum limit");
        }
    }

    /** 递归深度减一（不会抛出异常） */
    void decrement_depth() noexcept
    {
        if (_current_depth > 0)
        {
            --_current_depth;
        }
    }

    /** 检查是否未超过最大递归深度 */
    bool check_depth_limit() const noexcept { return _current_depth <= _max_depth; }

    /** 是否检测到已存在的引用（用于简单环检测） */
    bool has_circular_reference(const void * ptr) const noexcept
    {
        return _visited.find(ptr) != _visited.end();
    }

    /** 记录引用地址 */
    void add_reference(const void * ptr) { _visited.insert(ptr); }

    /** 移除引用地址 */
    void remove_reference(const void * ptr) { _visited.erase(ptr); }

    /** 增加对象处理计数 */
    void increment_objects_processed() noexcept { ++_objects_processed; }

    /** 增加字节处理计数 */
    void add_bytes_processed(std::size_t n) noexcept { _bytes_processed += n; }

    /** 获取统计值 */
    std::size_t bytes_processed() const noexcept { return _bytes_processed; }
    std::size_t objects_processed() const noexcept { return _objects_processed; }

private:
    std::size_t _current_depth;
    std::size_t _max_depth;
    std::unordered_set<const void *> _visited;
    std::size_t _bytes_processed;
    std::size_t _objects_processed;
};

/**
 * 线程局部的当前上下文指针
 * 说明: 作为内部机制用于在默认实现之间传递上下文。
 */
inline thread_local DefaultContext * g_current_context = nullptr;

/** 获取当前上下文指针（可能为 nullptr） */
inline DefaultContext *
get_current_context() noexcept
{
    return g_current_context;
}

/**
 * 上下文作用域守卫：在作用域内设置当前上下文并在退出时恢复
 */
class ContextScope
{
public:
    /**
     * 构造上下文作用域
     * 参数: ctx 需要设置为当前的上下文指针
     */
    explicit ContextScope(DefaultContext * ctx) noexcept : previous_(g_current_context)
    {
        g_current_context = ctx;
    }

    /** 析构时恢复之前的上下文指针 */
    ~ContextScope() { g_current_context = previous_; }

private:
    DefaultContext * previous_;
};

/**
 * 递归深度守卫：构造时递增深度并检查上限，析构时递减深度
 */
class RecursionDepthGuard
{
public:
    explicit RecursionDepthGuard(DefaultContext * ctx) : ctx_(ctx)
    {
        if (ctx_)
        {
            ctx_->increment_depth();
            ctx_->increment_objects_processed();
        }
    }
    ~RecursionDepthGuard()
    {
        if (ctx_)
        {
            ctx_->decrement_depth();
        }
    }

private:
    DefaultContext * ctx_;
};

// ============================================================================
// 长度前缀的可配置编码（固定 uint64_t 或 uLEB128 变长编码）
// ============================================================================

/**
 * 内部工具：判断是否启用变长长度编码
 * 参数: options 序列化选项
 * 返回值: true 启用变长编码；false 使用固定 64 位
 * 异常: 无
 */
template <typename Options>
constexpr bool
use_varint_lengths(const Options & options) noexcept
{
    if constexpr (serializer::detail::has_enable_varint_lengths<Options>::value)
    {
        return static_cast<bool>(options.enable_varint_lengths());
    }
    else
    {
        return false;
    }
}

/**
 * 将无符号 64 位整数使用 uLEB128 变长编码写入到 writer
 * 参数: writer 写入器
 * 参数: value 要写入的无符号 64 位整数
 * 返回值: 无
 * 异常: 可能抛出 writer.write_bytes 的异常
 */
template <typename Writer, typename std::enable_if<serializer::writer<Writer>, int>::type = 0>
inline void
write_varint_u64(Writer & writer, std::uint64_t value)
{
    std::byte buffer[10];
    std::size_t count = 0;
    while (value >= 0x80)
    {
        buffer[count++] = std::byte(static_cast<unsigned char>((value & 0x7Fu) | 0x80u));
        value >>= 7;
    }
    buffer[count++] = std::byte(static_cast<unsigned char>(value & 0x7Fu));
    writer.write_bytes(buffer, count);
}

/**
 * 从 reader 读取 uLEB128 变长编码的无符号 64 位整数
 * 参数: reader 读取器
 * 返回值: 解码得到的无符号 64 位整数
 * 异常: 当遇到无效编码（超过 10 字节或移位溢出）时抛出 std::runtime_error
 */
template <typename Reader, typename std::enable_if<serializer::reader<Reader>, int>::type = 0>
inline std::uint64_t
read_varint_u64(Reader & reader)
{
    std::uint64_t result = 0;
    int shift = 0;
    for (int i = 0; i < 10; ++i)
    {
        std::byte b{};
        reader.read_bytes(&b, 1);
        const std::uint8_t u = static_cast<std::uint8_t>(b);
        const std::uint8_t low7 = static_cast<std::uint8_t>(u & 0x7Fu);

        // 在 64 位上限边界进行严格溢出保护：
        // 1) 若当前移位为 63，仅允许最低 7 位为 0 或 1；
        // 2) 若当前移位为 63 且存在继续位（0x80），则必然溢出。
        if (shift == 63)
        {
            if ((u & 0x80u) != 0)
            {
                throw std::runtime_error("Invalid varint: overflow");
            }
            if (low7 > 1)
            {
                throw std::runtime_error("Invalid varint: overflow");
            }
        }

        result |= (static_cast<std::uint64_t>(low7) << shift);
        if ((u & 0x80u) == 0)
        {
            return result;
        }
        shift += 7;
    }
    throw std::runtime_error("Invalid varint: too many bytes");
}

/**
 * 写入长度前缀：当启用 varint 时使用 uLEB128，否则写入固定 64 位整型
 * 参数: writer 写入器
 * 参数: length 实际长度（size_t）
 * 参数: options 序列化选项
 * 返回值: 无
 * 异常: 可能抛出底层 writer/write 的异常
 */
template <typename Writer,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
inline void
write_length_prefix(Writer & writer, std::size_t length, const Options & options)
{
    const std::uint64_t length_u64 = static_cast<std::uint64_t>(length);
    if (use_varint_lengths(options))
    {
        write_varint_u64(writer, length_u64);
    }
    else
    {
        tag_invoke(serialize_tag, writer, length_u64, options);
    }
}

/**
 * 读取长度前缀：当启用 varint 时读取 uLEB128，否则读取固定 64 位整型
 * 参数: reader 读取器
 * 参数: max_allowed 允许的最大长度（用于安全检查）
 * 参数: options 序列化选项
 * 返回值: 以 size_t 表示的长度
 * 异常: 当长度超过 max_allowed 或无法在本平台表示为 size_t 时抛出 std::runtime_error
 */
template <typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
inline std::size_t
read_length_prefix(Reader & reader, std::size_t max_allowed, const Options & options)
{
    std::uint64_t length_u64{};
    if (use_varint_lengths(options))
    {
        length_u64 = read_varint_u64(reader);
    }
    else
    {
        length_u64 = tag_invoke(deserialize_tag<std::uint64_t>, reader, options);
    }

    if (length_u64 > static_cast<std::uint64_t>(std::numeric_limits<std::size_t>::max()))
    {
        throw std::runtime_error("Length exceeds platform size_t capacity");
    }

    const std::size_t length = static_cast<std::size_t>(length_u64);

    if (length > max_allowed)
    {
        throw std::runtime_error("Length exceeds maximum allowed size");
    }

    return length;
}

// =========================================================================
// 流头部（魔数/版本/字节序/标志）读写工具
// =========================================================================

/**
 * 流头部结构
 * 用于在数据流开头存储必要的格式信息，支持版本与特性协商。
 * 成员:
 * - version: 线格式版本号（建议从 1 开始）
 * - payload_byte_order: 后续载荷所采用的字节序（与 options.get_byte_order 的有效值一致）
 * - varint_lengths_enabled: 是否启用变长长度字段编码（uLEB128）
 * - checksum_enabled: 是否启用校验（保留位，当前库不强制实现）
 * - debug_enabled: 是否启用调试标志（保留位）
 */
struct stream_header
{
    std::uint32_t version = 1;
    byte_order payload_byte_order = byte_order::little_endian;
    bool varint_lengths_enabled = false;
    bool checksum_enabled = false;
    bool debug_enabled = false;
};

/**
 * 将 32 位整数以小端序写入（与 options 无关，头部采用固定 LE 编码）
 * 参数: writer 写入器
 * 参数: value 要写入的值
 * 返回值: 无
 * 异常: 可能抛出 writer.write_bytes 的异常
 */
template <typename Writer, typename std::enable_if<serializer::writer<Writer>, int>::type = 0>
inline void
write_u32_le(Writer & writer, std::uint32_t value)
{
    std::byte bytes[4]{
        std::byte(static_cast<unsigned char>(value & 0xFFu)),
        std::byte(static_cast<unsigned char>((value >> 8) & 0xFFu)),
        std::byte(static_cast<unsigned char>((value >> 16) & 0xFFu)),
        std::byte(static_cast<unsigned char>((value >> 24) & 0xFFu)),
    };
    writer.write_bytes(bytes, 4);
}

/**
 * 从读取器以小端序读取 32 位整数（与 options 无关，头部采用固定 LE 编码）
 * 参数: reader 读取器
 * 返回值: 读取到的 32 位整数
 * 异常: 可能抛出 reader.read_bytes 的异常
 */
template <typename Reader, typename std::enable_if<serializer::reader<Reader>, int>::type = 0>
inline std::uint32_t
read_u32_le(Reader & reader)
{
    std::byte bytes[4]{};
    reader.read_bytes(bytes, 4);
    std::uint32_t value = 0;
    value |= static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[0]));
    value |= static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[1])) << 8;
    value |= static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[2])) << 16;
    value |= static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[3])) << 24;
    return value;
}

/**
 * 写入流头部（魔数/版本/字节序/特性标志）
 * 参数: writer 写入器
 * 参数: options 序列化选项（用于读取版本与特性标志）
 * 返回值: 无
 * 异常: 可能抛出 writer.write_bytes 的异常
 */
template <typename Writer,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
inline void
write_stream_header(Writer & writer, const Options & options)
{
    // 魔数：固定 "SRLZ"
    const std::byte magic[4]{static_cast<std::byte>('S'),
                             static_cast<std::byte>('R'),
                             static_cast<std::byte>('L'),
                             static_cast<std::byte>('Z')};
    writer.write_bytes(magic, 4);

    // 版本：若 options 提供 version()，则使用；否则默认 1（LE 编码）
    std::uint32_t version = 1;
    if constexpr (serializer::detail::has_version_u32<Options>::value)
    {
        version = static_cast<std::uint32_t>(options.version());
    }
    write_u32_le(writer, version);

    // 特性标志位：bit0=varint_lengths, bit1=checksum, bit2=debug
    std::uint32_t flags = 0;
    if constexpr (serializer::detail::has_enable_varint_lengths<Options>::value)
    {
        if (static_cast<bool>(options.enable_varint_lengths()))
        {
            flags |= 0x1u;
        }
    }
    if constexpr (serializer::detail::has_enable_checksum<Options>::value)
    {
        if (static_cast<bool>(options.enable_checksum()))
        {
            flags |= 0x2u;
        }
    }
    if constexpr (serializer::detail::has_enable_debug<Options>::value)
    {
        if (static_cast<bool>(options.enable_debug()))
        {
            flags |= 0x4u;
        }
    }
    write_u32_le(writer, flags);

    // 字节序：记录载荷字节序（将 native 映射为显式 little/big）
    byte_order order = options.get_byte_order();
    if (order == byte_order::native)
    {
        order = native_byte_order();
    }
    const std::uint8_t order_byte = (order == byte_order::little_endian) ? 0u : 1u;
    const std::byte order_b = std::byte(order_byte);
    writer.write_bytes(&order_b, 1);

    // 预留字节以便后续扩展（当前写入 3 字节 0，使头部长度为 4+4+4+1+3=16 字节）
    const std::byte reserved[3]{std::byte{0}, std::byte{0}, std::byte{0}};
    writer.write_bytes(reserved, 3);
}

/**
 * 读取流头部（魔数/版本/字节序/特性标志）
 * 参数: reader 读取器
 * 返回值: 解析得到的流头部信息
 * 异常: 当魔数不匹配、字节序字段非法或读取失败时抛出 std::runtime_error
 */
template <typename Reader, typename std::enable_if<serializer::reader<Reader>, int>::type = 0>
inline stream_header
read_stream_header(Reader & reader)
{
    // 读取并校验魔数
    std::byte magic[4]{};
    reader.read_bytes(magic, 4);
    const std::byte expected[4]{static_cast<std::byte>('S'),
                                static_cast<std::byte>('R'),
                                static_cast<std::byte>('L'),
                                static_cast<std::byte>('Z')};
    if (!(magic[0] == expected[0] && magic[1] == expected[1] && magic[2] == expected[2] &&
          magic[3] == expected[3]))
    {
        throw std::runtime_error("Invalid stream header magic");
    }

    stream_header header{};
    header.version = read_u32_le(reader);
    const std::uint32_t flags = read_u32_le(reader);

    std::byte order_byte{};
    reader.read_bytes(&order_byte, 1);
    const std::uint8_t ob = static_cast<std::uint8_t>(order_byte);
    if (ob == 0)
    {
        header.payload_byte_order = byte_order::little_endian;
    }
    else if (ob == 1)
    {
        header.payload_byte_order = byte_order::big_endian;
    }
    else
    {
        throw std::runtime_error("Invalid byte order in stream header");
    }

    // 读取保留字节（当前忽略）
    std::byte reserved[3]{};
    reader.read_bytes(reserved, 3);

    // 解析标志位
    header.varint_lengths_enabled = (flags & 0x1u) != 0;
    header.checksum_enabled = (flags & 0x2u) != 0;
    header.debug_enabled = (flags & 0x4u) != 0;

    return header;
}

/**
 * 根据流头部信息生成用于后续载荷的有效 default_options
 * 将头部中的字节序与 varint 设置应用到新的 default_options，并保留原 options 的大小/深度限制。
 * 参数: base_options 基础选项（提供大小限制等）
 * 参数: header 解析得到的流头部
 * 返回值: 应用头部后的 default_options 对象
 * 异常: 无
 */
template <typename Options>
inline default_options
apply_stream_header_to_options(const Options & base_options, const stream_header & header) noexcept
{
    default_options eff{};
    eff =
        eff.with_byte_order(header.payload_byte_order)
            .with_varint_lengths(header.varint_lengths_enabled)
            .with_max_container_size(static_cast<std::size_t>(base_options.max_container_size()))
            .with_max_string_length(static_cast<std::size_t>(base_options.max_string_length()))
            .with_max_recursion_depth(static_cast<std::size_t>(base_options.max_recursion_depth()));
    return eff;
}

/**
 * 写入完整流（头部 + 载荷）
 * 参数: writer 写入器
 * 参数: value 要序列化的对象
 * 参数: options 序列化选项（版本、字节序、varint 等会被写入头部）
 * 返回值: 无
 * 异常: 可能抛出底层 write_bytes 或具体类型序列化过程中的异常
 */
template <typename Writer,
          typename T,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
inline void
write_stream(Writer & writer, const T & value, const Options & options)
{
    write_stream_header(writer, options);
    // 在写入载荷期间建立上下文，应用递归深度限制
    DefaultContext ctx(options.max_recursion_depth());
    ContextScope scope(&ctx);
    tag_invoke(serialize_tag, writer, value, options);
}

/**
 * 读取严格版完整流（必须存在头部）
 * - 流必须以 SRLZ 头部开头；若魔数不匹配或头部非法则抛出异常。
 * 参数: reader 读取器
 * 参数: base_options 基础选项（用于容量/字符串长度/递归深度等限制；字节序与 varint
 * 策略将由头部覆盖） 返回值: 反序列化得到的对象 异常: 当魔数不匹配或头部字段非法时抛出
 * std::runtime_error；同时可能抛出底层 read_bytes 或具体类型反序列化过程中的异常
 */
template <typename T,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
inline T
read_stream(Reader & reader, const Options & base_options)
{
    const stream_header header = read_stream_header(reader);
    const auto effective_options = apply_stream_header_to_options(base_options, header);
    DefaultContext ctx(effective_options.max_recursion_depth());
    ContextScope scope(&ctx);
    return tag_invoke(deserialize_tag<T>, reader, effective_options);
}

// ============================================================================
// 算术类型的默认实现（仅限可移植算术类型：整数 + IEEE754 float/double）
// =============================================================================

template <
    typename Writer,
    typename T,
    typename Options,
    typename std::enable_if<serializer::writer<Writer> && serializer::portable_arithmetic_type<T> &&
                                serializer::serialization_options<Options>,
                            int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const T & value, const Options & options)
{
    // 参数:
    //  - writer: 写入器
    //  - value: 待序列化的数值（整数或 float/double）
    //  - options: 选项，决定目标字节序
    // 返回值: 无
    // 异常: 底层 writer 可能抛出 I/O 异常
    // 说明: 对 long double 默认不支持（不满足 portable_arithmetic_type），需用户自定义 tag_invoke
    // 或转换为 double 存储。
    T converted_value = convert_byte_order(value, options.get_byte_order());
    const auto * bytes = reinterpret_cast<const std::byte *>(&converted_value);
    writer.write_bytes(bytes, sizeof(T));
}

template <
    typename T,
    typename Reader,
    typename Options,
    typename std::enable_if<serializer::portable_arithmetic_type<T> && serializer::reader<Reader> &&
                                serializer::serialization_options<Options>,
                            int>::type = 0>
T

tag_invoke(deserialize_tag_t<T>, Reader & reader, const Options & options)
{
    // 参数:
    //  - reader: 读取器
    //  - options: 选项，提供载荷字节序
    // 返回值: 反序列化得到的数值
    // 异常: 底层 reader 可能抛出 I/O 异常
    // 说明: 对 long double 默认不支持（不满足 portable_arithmetic_type），需用户自定义。
    T value{};
    auto * bytes = reinterpret_cast<std::byte *>(&value);
    reader.read_bytes(bytes, sizeof(T));
    return convert_byte_order(value, options.get_byte_order());
}

// ============================================================================
// 字符串类型的默认实现
// ============================================================================

template <typename Writer,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void
tag_invoke(serialize_tag_t, Writer & writer, const std::string & value, const Options & options)
{
    const std::size_t length = value.size();
    if (length > options.max_string_length())
    {
        throw std::runtime_error("String length exceeds maximum allowed size");
    }

    write_length_prefix(writer, length, options);

    if (length > 0)
    {
        const auto * bytes = reinterpret_cast<const std::byte *>(value.data());
        writer.write_bytes(bytes, length);
    }
}

template <typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::string

tag_invoke(deserialize_tag_t<std::string>, Reader & reader, const Options & options)
{
    const std::size_t length = read_length_prefix(reader, options.max_string_length(), options);

    std::string result;
    if (length > 0)
    {
        result.resize(length);
        auto * bytes = reinterpret_cast<std::byte *>(result.data());
        reader.read_bytes(bytes, length);
    }

    return result;
}

// ============================================================================
// 容器类型的默认实现
// ============================================================================

/**
 * 连续字节序列容器的序列化（value_type 为 std::byte）
 * - 针对具有连续内存布局且元素为 std::byte 的容器，直接整块写入。
 * 参数: writer 写入器
 * 参数: container 容器（要求具有 data() 且迭代器为连续迭代器）
 * 参数: options 序列化选项（包含最大容器容量、长度编码策略等）
 * 返回值: 无
 * 异常: 当容器大小超过 options.max_container_size() 或检测到循环引用时抛出
 * std::runtime_error；也可能抛出底层写入异常
 */
template <typename Writer,
          typename Container,
          typename Options,
          typename std::enable_if<
              serializer::writer<Writer> && serializer::serialization_options<Options> &&
                  serializer::ContiguousSequenceContainer<Container> &&
                  std::is_same<typename Container::value_type, std::byte>::value,
              int>::type = 0>
void
tag_invoke(serialize_tag_t, Writer & writer, const Container & container, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = container.size();
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Container size exceeds maximum allowed size");
    }

    if (ctx)
    {
        if (ctx->has_circular_reference(&container))
        {
            throw std::runtime_error(
                "Circular reference detected while serializing contiguous byte container");
        }
        ctx->add_reference(&container);
    }

    write_length_prefix(writer, size, options);

    if (size > 0)
    {
        const std::byte * data_ptr = container.data();
        writer.write_bytes(data_ptr, size);
    }

    if (ctx)
    {
        ctx->remove_reference(&container);
    }
}

/**
 * 算术类型的连续序列容器的序列化（如 std::vector<int> 等）
 * - 针对具有连续内存布局且元素为算术类型的容器，进行块拷贝优化。
 * - 当目标字节序为 native 或元素为 1 字节时，直接整块写入；否则逐元素转换后一次性写入。
 * 参数: writer 写入器
 * 参数: container 容器（要求具有 data() 且迭代器为连续迭代器）
 * 参数: options 序列化选项（包含最大容器容量、长度编码策略、字节序设置等）
 * 返回值: 无
 * 异常: 当容器大小超过 options.max_container_size() 或检测到循环引用时抛出
 * std::runtime_error；也可能抛出底层写入异常
 */
template <typename Writer,
          typename Container,
          typename Options,
          typename std::enable_if<
              serializer::writer<Writer> && serializer::serialization_options<Options> &&
                  serializer::ContiguousSequenceContainer<Container> &&
                  serializer::portable_arithmetic_type<typename Container::value_type> &&
                  !std::is_same<typename Container::value_type, std::byte>::value,
              int>::type = 0>
void
tag_invoke(serialize_tag_t, Writer & writer, const Container & container, const Options & options)
{
    // 参数: writer 写入器; container 连续容器; options 选项
    // 返回值: 无
    // 异常: 容量越界/循环引用检测/底层 I/O 异常
    // 说明: 元素类型为整数或受支持的 IEEE754 浮点（float/double）；long double 默认不支持。
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = container.size();
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Container size exceeds maximum allowed size");
    }

    if (ctx)
    {
        if (ctx->has_circular_reference(&container))
        {
            throw std::runtime_error(
                "Circular reference detected while serializing arithmetic contiguous container");
        }
        ctx->add_reference(&container);
    }

    write_length_prefix(writer, size, options);

    using value_type = typename Container::value_type;
    const auto target_order = options.get_byte_order();
    const std::size_t total_bytes = size * sizeof(value_type);

    if (size == 0)
    {
        if (ctx)
            ctx->remove_reference(&container);
        return;
    }

    if (target_order == byte_order::native || target_order == native_byte_order() ||
        sizeof(value_type) == 1)
    {
        const std::byte * data_ptr = reinterpret_cast<const std::byte *>(container.data());
        writer.write_bytes(data_ptr, total_bytes);
    }
    else
    {
        std::vector<std::byte> buffer(total_bytes);
        const value_type * src = container.data();
        for (std::size_t i = 0; i < size; ++i)
        {
            value_type converted = convert_byte_order(src[i], target_order);
            std::memcpy(buffer.data() + i * sizeof(value_type), &converted, sizeof(value_type));
        }
        writer.write_bytes(buffer.data(), buffer.size());
    }

    if (ctx)
    {
        ctx->remove_reference(&container);
    }
}

// 算术类型的连续容器（非 std::byte）的反序列化：块读取 + 逐元素字节序转换
template <typename Container,
          typename Reader,
          typename Options,
          typename std::enable_if<
              serializer::ContiguousSequenceContainer<Container> && serializer::reader<Reader> &&
                  serializer::serialization_options<Options> &&
                  serializer::portable_arithmetic_type<typename Container::value_type> &&
                  !std::is_same<typename Container::value_type, std::byte>::value,
              int>::type = 0>
Container

tag_invoke(deserialize_tag_t<Container>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = read_length_prefix(reader, options.max_container_size(), options);

    using value_type = typename Container::value_type;
    const auto target_order = options.get_byte_order();
    const std::size_t total_bytes = size * sizeof(value_type);

    Container result;
    if constexpr (HasReserve<Container>::value)
    {
        result.reserve(size);
    }
    if constexpr (HasResize<Container>::value)
    {
        result.resize(size);
        std::byte * data_ptr = reinterpret_cast<std::byte *>(result.data());
        if (size > 0)
        {
            reader.read_bytes(data_ptr, total_bytes);
            if (!(target_order == byte_order::native || target_order == native_byte_order() ||
                  sizeof(value_type) == 1))
            {
                for (std::size_t i = 0; i < size; ++i)
                {
                    result[i] = convert_byte_order(result[i], target_order);
                }
            }
        }
    }
    else
    {
        // 回退路径：若容器不支持 resize，则逐元素读取
        for (std::size_t i = 0; i < size; ++i)
        {
            auto elem = tag_invoke(deserialize_tag<value_type>, reader, options);
            if constexpr (HasPushBack<Container>::value)
            {
                result.push_back(std::move(elem));
            }
            else if constexpr (HasInsert<Container>::value)
            {
                result.insert(result.end(), std::move(elem));
            }
        }
    }

    return result;
}

// 连续字节序列容器（std::byte）的反序列化：直接块读取
template <typename Container,
          typename Reader,
          typename Options,
          typename std::enable_if<
              serializer::ContiguousSequenceContainer<Container> && serializer::reader<Reader> &&
                  serializer::serialization_options<Options> &&
                  std::is_same<typename Container::value_type, std::byte>::value,
              int>::type = 0>
Container

tag_invoke(deserialize_tag_t<Container>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = read_length_prefix(reader, options.max_container_size(), options);

    Container result;
    if constexpr (HasReserve<Container>::value)
    {
        result.reserve(size);
    }
    if constexpr (HasResize<Container>::value)
    {
        result.resize(size);
        std::byte * data_ptr = result.data();
        if (size > 0)
        {
            reader.read_bytes(data_ptr, size);
        }
    }
    else
    {
        // 回退路径：若容器不支持 resize，则逐元素读取
        for (std::size_t i = 0; i < size; ++i)
        {
            auto b = tag_invoke(deserialize_tag<std::byte>, reader, options);
            if constexpr (HasPushBack<Container>::value)
            {
                result.push_back(b);
            }
            else if constexpr (HasInsert<Container>::value)
            {
                result.insert(result.end(), b);
            }
        }
    }

    return result;
}

template <typename Writer,
          typename Container,
          typename Options,
          typename std::enable_if<
              serializer::writer<Writer> && serializer::serialization_options<Options> &&
                  serializer::SequenceContainer<Container> &&
                  !(serializer::ContiguousSequenceContainer<Container> &&
                    (serializer::portable_arithmetic_type<typename Container::value_type> ||
                     std::is_same<typename Container::value_type, std::byte>::value)),
              int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const Container & container, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = container.size();
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Container size exceeds maximum allowed size");
    }

    if (ctx)
    {
        if (ctx->has_circular_reference(&container))
        {
            throw std::runtime_error(
                "Circular reference detected while serializing sequence container");
        }
        ctx->add_reference(&container);
    }

    write_length_prefix(writer, size, options);

    for (const auto & element : container)
    {
        tag_invoke(serialize_tag, writer, element, options);
    }

    if (ctx)
    {
        ctx->remove_reference(&container);
    }
}

template <typename Container,
          typename Reader,
          typename Options,
          typename std::enable_if<
              serializer::SequenceContainer<Container> &&
                  !(serializer::ContiguousSequenceContainer<Container> &&
                    (serializer::portable_arithmetic_type<typename Container::value_type> ||
                     std::is_same<typename Container::value_type, std::byte>::value)) &&
                  serializer::reader<Reader> && serializer::serialization_options<Options>,
              int>::type = 0>
Container

tag_invoke(deserialize_tag_t<Container>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = read_length_prefix(reader, options.max_container_size(), options);

    Container result;

    for (std::size_t i = 0; i < size; ++i)
    {
        using value_type = typename Container::value_type;
        auto element = tag_invoke(deserialize_tag<value_type>, reader, options);

        if constexpr (HasPushBack<Container>::value)
        {
            result.push_back(std::move(element));
        }
        else if constexpr (HasInsert<Container>::value)
        {
            result.insert(result.end(), std::move(element));
        }
        else
        {
            static_assert(sizeof(Container) == 0,
                          "Container type not supported for deserialization");
        }
    }

    return result;
}

template <typename Writer,
          typename Container,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options> &&
                                      serializer::AssociativeContainer<Container>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const Container & container, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = container.size();
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Container size exceeds maximum allowed size");
    }

    if (ctx)
    {
        if (ctx->has_circular_reference(&container))
        {
            throw std::runtime_error(
                "Circular reference detected while serializing associative container");
        }
        ctx->add_reference(&container);
    }

    write_length_prefix(writer, size, options);

    for (const auto & element : container)
    {
        tag_invoke(serialize_tag, writer, element, options);
    }

    if (ctx)
    {
        ctx->remove_reference(&container);
    }
}

template <typename Container,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::AssociativeContainer<Container> &&
                                      serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
Container

tag_invoke(deserialize_tag_t<Container>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = read_length_prefix(reader, options.max_container_size(), options);

    Container result;

    if constexpr (HasReserve<Container>::value)
    {
        result.reserve(size);
    }

    for (std::size_t i = 0; i < size; ++i)
    {
        if constexpr (MapContainer<Container>)
        {
            using key_type = typename Container::key_type;
            using mapped_type = typename Container::mapped_type;
            using nonconst_key_type = std::remove_const_t<key_type>;

            auto key = tag_invoke(deserialize_tag<nonconst_key_type>, reader, options);
            auto value = tag_invoke(deserialize_tag<mapped_type>, reader, options);
            result.emplace(std::move(key), std::move(value));
        }
        else if constexpr (SetContainer<Container>)
        {
            using key_type = typename Container::key_type;
            auto key = tag_invoke(deserialize_tag<key_type>, reader, options);
            result.insert(std::move(key));
        }
        else
        {
            static_assert(sizeof(Container) == 0, "Unsupported associative container type");
        }
    }

    return result;
}

// ============================================================================
// std::pair 的默认实现
// ============================================================================

template <typename Writer,
          typename T1,
          typename T2,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options> &&
                                      !serializer::BasicContainer<std::pair<T1, T2>>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::pair<T1, T2> & pair,
           const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    tag_invoke(serialize_tag, writer, pair.first, options);
    tag_invoke(serialize_tag, writer, pair.second, options);
}

template <typename T1,
          typename T2,
          typename Reader,
          typename Options,
          typename std::enable_if<!serializer::BasicContainer<std::pair<T1, T2>> &&
                                      serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::pair<T1, T2>

tag_invoke(deserialize_tag_t<std::pair<T1, T2>>, Reader & reader, const Options & options)
{
    using first_nonconst_t = std::remove_const_t<T1>;
    auto first = tag_invoke(deserialize_tag<first_nonconst_t>, reader, options);
    auto second = tag_invoke(deserialize_tag<T2>, reader, options);
    return std::pair<T1, T2>{std::move(first), std::move(second)};
}

// ============================================================================
// std::optional 的默认实现
// ============================================================================

template <typename Writer,
          typename T,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const std::optional<T> & opt, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const bool has_value = opt.has_value();
    tag_invoke(serialize_tag, writer, has_value, options);
    if (has_value)
    {
        tag_invoke(serialize_tag, writer, *opt, options);
    }
}

template <typename T,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::optional<T>

tag_invoke(deserialize_tag_t<std::optional<T>>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const bool has_value = tag_invoke(deserialize_tag<bool>, reader, options);
    if (!has_value)
    {
        return std::optional<T>{};
    }
    return std::optional<T>{tag_invoke(deserialize_tag<T>, reader, options)};
}

// ============================================================================
// std::byte 的默认实现
// ============================================================================

template <typename Writer,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const std::byte & value, const Options & options)
{
    (void)options;
    writer.write_bytes(&value, 1);
}

template <typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::byte

tag_invoke(deserialize_tag_t<std::byte>, Reader & reader, const Options & options)
{
    (void)options;
    std::byte value{};
    reader.read_bytes(&value, 1);
    return value;
}

// ============================================================================
// std::array 的默认实现
// ============================================================================

/*
函数说明: 序列化 std::array 为长度前缀 + 数据块。对 std::byte
类型零拷贝写入；对算术类型在目标字节序为 native 或元素大小为 1
字节时零拷贝，否则进行批量字节序转换后一次性写入。 参数:
- writer: 写入器，必须提供 write_bytes 等接口
- arr: 要序列化的数组
- options: 序列化选项，使用其中的 byte_order 与长度前缀策略
返回值:
- 无
异常:
- 可能抛出 writer 的底层 I/O 异常
*/
template <typename Writer,
          typename Options,
          typename T,
          std::size_t N,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const std::array<T, N> & arr, const Options & options)
{
    write_length_prefix(writer, N, options);

    if constexpr (std::is_same<T, std::byte>::value)
    {
        // std::byte 类型零拷贝写入
        writer.write_bytes(arr.data(), N);
        return;
    }
    else if constexpr (serializer::portable_arithmetic_type<T>)
    {
        // 算术类型在 native 字节序或元素为 1 字节时直接块写
        if (options.get_byte_order() == byte_order::native || sizeof(T) == 1)
        {
            writer.write_bytes(reinterpret_cast<const std::byte *>(arr.data()), N * sizeof(T));
            return;
        }

        // 目标字节序与本机字节序不同，批量转换后一次性写入
        std::array<T, N> converted{};
        for (std::size_t i = 0; i < N; ++i)
        {
            converted[i] = convert_byte_order<T>(arr[i], options.get_byte_order());
        }
        writer.write_bytes(reinterpret_cast<const std::byte *>(converted.data()), N * sizeof(T));
        return;
    }

    // 非算术类型逐元素序列化
    for (const auto & elem : arr)
    {
        tag_invoke(serialize_tag, writer, elem, options);
    }
}

template <typename T,
          std::size_t N,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::array<T, N>

tag_invoke(deserialize_tag_t<std::array<T, N>>, Reader & reader, const Options & options)
{
    const std::size_t size = read_length_prefix(reader, N, options);
    if (size != N)
    {
        throw std::runtime_error("Deserialized array size does not match static array size");
    }

    std::array<T, N> arr{};
    for (std::size_t i = 0; i < N; ++i)
    {
        arr[i] = tag_invoke(deserialize_tag<T>, reader, options);
    }
    return arr;
}

// ============================================================================
// std::tuple 的默认实现
// ============================================================================

template <typename Writer,
          typename Options,
          typename... Ts,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const std::tuple<Ts...> & tpl, const Options & options)
{
    constexpr std::size_t tuple_size = sizeof...(Ts);
    static_assert(tuple_size >= 0, "tuple size must be non-negative");

    const std::size_t size = tuple_size;
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Tuple size exceeds maximum allowed size");
    }
    write_length_prefix(writer, size, options);

    [&]<std::size_t... Is>(std::index_sequence<Is...>)
    {
        (tag_invoke(serialize_tag, writer, std::get<Is>(tpl), options), ...);
    }
    (std::make_index_sequence<tuple_size>{});
}

template <typename... Ts,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::tuple<Ts...>

tag_invoke(deserialize_tag_t<std::tuple<Ts...>>, Reader & reader, const Options & options)
{
    constexpr std::size_t tuple_size = sizeof...(Ts);
    const std::size_t size = read_length_prefix(reader, options.max_container_size(), options);
    if (size != tuple_size)
    {
        throw std::runtime_error("Deserialized tuple size does not match static tuple size");
    }

    return std::tuple<Ts...>{tag_invoke(deserialize_tag<Ts>, reader, options)...};
}

// ============================================================================
// 适配器容器（stack/queue/priority_queue）的默认实现
// ============================================================================

template <typename Writer,
          typename Options,
          typename Adapter,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options> &&
                                      AdapterContainer<Adapter>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const Adapter & adapter, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    using container_type = typename Adapter::container_type;
    using value_type = typename Adapter::value_type;

    // 基于公开接口复制出线性视图，不依赖适配器内部布局
    container_type underlying_copy = [&]()
    {
        if constexpr (StackAdapter<Adapter>)
        {
            std::vector<value_type> temp;
            auto copy = adapter;
            while (!copy.empty())
            {
                temp.push_back(copy.top());
                copy.pop();
            }
            return container_type(temp.rbegin(), temp.rend());
        }
        else if constexpr (QueueAdapter<Adapter>)
        {
            std::vector<value_type> temp;
            auto copy = adapter;
            while (!copy.empty())
            {
                temp.push_back(copy.front());
                copy.pop();
            }
            return container_type(temp.begin(), temp.end());
        }
        else if constexpr (PriorityQueueAdapter<Adapter>)
        {
            std::vector<value_type> temp;
            auto copy = adapter;
            while (!copy.empty())
            {
                temp.push_back(copy.top());
                copy.pop();
            }
            return container_type(temp.begin(), temp.end());
        }
    }();

    if (ctx)
    {
        if (ctx->has_circular_reference(&adapter) || ctx->has_circular_reference(&underlying_copy))
        {
            throw std::runtime_error(
                "Circular reference detected while serializing adapter container");
        }
        ctx->add_reference(&adapter);
        ctx->add_reference(&underlying_copy);
    }

    tag_invoke(serialize_tag, writer, underlying_copy, options);

    if (ctx)
    {
        ctx->remove_reference(&underlying_copy);
        ctx->remove_reference(&adapter);
    }
}

template <typename Adapter,
          typename Reader,
          typename Options,
          typename = std::enable_if_t<AdapterContainer<Adapter> && serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>>>
Adapter
tag_invoke(deserialize_tag_t<Adapter>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    using container_type = typename Adapter::container_type;
    auto underlying = tag_invoke(deserialize_tag<container_type>, reader, options);
    return reconstruct_adapter_from_container<Adapter>(std::move(underlying));
}

// =============================================================================
// std::variant 的默认实现（先写入 index，再写入当前持有值）
// =============================================================================

template <typename Writer,
          typename Options,
          typename... Ts,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::variant<Ts...> & value,
           const Options & options)
{
    // 参数:
    //  - writer: 写入器
    //  - value: 待序列化的 variant 值
    //  - options: 序列化选项
    // 返回值: 无
    // 异常: 底层 I/O 可能抛出异常；若内部成员序列化失败也可能抛出异常
    // 说明: 先写入当前激活成员的 index（uint32），再写入对应成员的值

    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    using index_type = std::uint32_t;
    static_assert(std::variant_size_v<std::variant<Ts...>> <=
                      std::numeric_limits<index_type>::max(),
                  "variant alternative count exceeds uint32_t capacity");

    const index_type active_index = static_cast<index_type>(value.index());
    tag_invoke(serialize_tag, writer, active_index, options);

    std::visit([&](const auto & held) { tag_invoke(serialize_tag, writer, held, options); }, value);
}

template <typename Variant,
          typename Reader,
          typename Options,
          std::size_t... Is,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
static Variant
construct_variant_by_index(std::uint32_t index,
                           Reader & reader,
                           const Options & options,
                           std::index_sequence<Is...>)
{
    // 参数:
    //  - index: 需要构造的备选项序号
    //  - reader: 读取器
    //  - options: 选项
    //  - Is...: 变参索引序列
    // 返回值: 按 index 读取并构造出的 Variant 对象
    // 异常: 若 index 越界或内部成员反序列化失败将抛出异常

    using constructor_fn = Variant (*)(Reader &, const Options &);
    static constexpr constructor_fn ctors[] = {
        +[](Reader & r, const Options & opt) -> Variant
        {
            using alt_t = std::variant_alternative_t<Is, Variant>;
            auto v = tag_invoke(deserialize_tag<alt_t>, r, opt);
            return Variant{std::in_place_index<Is>, std::move(v)};
        }...};

    if (index >= sizeof...(Is))
    {
        throw std::runtime_error("variant index out of range during deserialization");
    }
    return ctors[index](reader, options);
}

template <typename... Ts,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::variant<Ts...>

tag_invoke(deserialize_tag_t<std::variant<Ts...>>, Reader & reader, const Options & options)
{
    // 参数:
    //  - reader: 读取器
    //  - options: 选项
    // 返回值: 反序列化得到的 variant
    // 异常: 当索引越界或成员反序列化失败时抛出异常
    // 说明: 先读取 index（uint32），然后根据 index 读取对应成员的值

    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    using index_type = std::uint32_t;
    const index_type index = tag_invoke(deserialize_tag<index_type>, reader, options);
    using variant_t = std::variant<Ts...>;
    return construct_variant_by_index<variant_t>(
        index, reader, options, std::make_index_sequence<std::variant_size_v<variant_t>>{});
}

// =============================================================================
// std::chrono::duration 的默认实现（统一按纳秒计数进行持久化）
// =============================================================================

template <typename Writer,
          typename Options,
          typename Rep,
          typename Period,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::chrono::duration<Rep, Period> & duration,
           const Options & options)
{
    // 参数:
    //  - writer: 写入器
    //  - duration: 任意周期与表示类型的 duration
    //  - options: 选项
    // 返回值: 无
    // 异常: 底层 I/O 可能抛出异常
    // 说明: 统一转换为 std::chrono::nanoseconds 后，写入 int64 计数；
    //       该策略简单可移植，但当值超出 int64 纳秒范围时行为未定义（可能溢出）。

    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const auto ns = std::chrono::duration_cast<std::chrono::nanoseconds>(duration);
    const std::int64_t ticks = ns.count();
    tag_invoke(serialize_tag, writer, ticks, options);
}

template <typename Rep,
          typename Period,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::chrono::duration<Rep, Period>

tag_invoke(deserialize_tag_t<std::chrono::duration<Rep, Period>>,
           Reader & reader,
           const Options & options)
{
    // 参数:
    //  - reader: 读取器
    //  - options: 选项
    // 返回值: 反序列化得到的 duration 对象
    // 异常: 底层 I/O 可能抛出异常
    // 说明: 从 int64 纳秒计数读取并转换为目标周期与表示类型；
    //       若存在精度损失，将按 std::chrono::duration_cast 的语义舍入/截断。

    const std::int64_t ticks = tag_invoke(deserialize_tag<std::int64_t>, reader, options);
    const auto ns = std::chrono::nanoseconds{ticks};
    return std::chrono::duration_cast<std::chrono::duration<Rep, Period>>(ns);
}

// =============================================================================
// std::chrono::time_point 的默认实现（以自纪元起纳秒计数进行持久化）
// =============================================================================

template <typename Writer,
          typename Options,
          typename Clock,
          typename Duration,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::chrono::time_point<Clock, Duration> & tp,
           const Options & options)
{
    // 参数:
    //  - writer: 写入器
    //  - tp: 任意时钟/周期的 time_point
    //  - options: 选项
    // 返回值: 无
    // 异常: 底层 I/O 可能抛出异常
    // 说明: 将 time_since_epoch() 统一转换为纳秒计数并写入 int64；
    //       对于非实时时钟（如 steady_clock），该值仅具有相对意义，跨进程/跨机器不可比。

    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const auto since_epoch = tp.time_since_epoch();
    const auto ns = std::chrono::duration_cast<std::chrono::nanoseconds>(since_epoch);
    const std::int64_t ticks = ns.count();
    tag_invoke(serialize_tag, writer, ticks, options);
}

template <typename Clock,
          typename Duration,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::chrono::time_point<Clock, Duration>

tag_invoke(deserialize_tag_t<std::chrono::time_point<Clock, Duration>>,
           Reader & reader,
           const Options & options)
{
    // 参数:
    //  - reader: 读取器
    //  - options: 选项
    // 返回值: 反序列化得到的 time_point 对象
    // 异常: 底层 I/O 可能抛出异常
    // 说明: 从 int64 纳秒计数读取并转换为目标时钟/周期的 time_point；
    //       对 steady_clock 等单调时钟，其绝对值无移植性，仅用于相对时间。

    const std::int64_t ticks = tag_invoke(deserialize_tag<std::int64_t>, reader, options);
    const auto ns = std::chrono::nanoseconds{ticks};
    const auto dur = std::chrono::duration_cast<Duration>(ns);
    return std::chrono::time_point<Clock, Duration>{dur};
}

// =============================================================================
// std::bitset 的默认实现
// =============================================================================

template <typename Writer,
          typename Options,
          std::size_t N,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t, Writer & writer, const std::bitset<N> & bits, const Options & options)
{
    // 参数: writer 写入器; bits 固定位集合; options 选项
    // 返回值: 无
    // 异常: 底层 I/O 异常
    // 说明: 写入长度前缀 N，然后以字节打包位数据。位 i 映射到字节 (i/8) 的位
    // (i%8)，低位在前；字节序设置对位集编码无影响。
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    write_length_prefix(writer, N, options);

    const std::size_t bytes_count = (N + 7) / 8;
    std::vector<std::byte> buffer(bytes_count, std::byte{0});

    for (std::size_t i = 0; i < N; ++i)
    {
        if (bits.test(i))
        {
            const std::size_t byte_index = i / 8;
            const unsigned bit_in_byte = static_cast<unsigned>(i % 8);
            buffer[byte_index] |= static_cast<std::byte>(1u << bit_in_byte);
        }
    }

    if (!buffer.empty())
    {
        writer.write_bytes(buffer.data(), buffer.size());
    }
}

template <std::size_t N,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::bitset<N>

tag_invoke(deserialize_tag_t<std::bitset<N>>, Reader & reader, const Options & options)
{
    // 参数: reader 读取器; options 选项
    // 返回值: 反序列化得到的 bitset<N>
    // 异常: 长度不匹配/底层 I/O 异常
    // 说明: 读取长度前缀并校验是否为 N，然后读取打包字节并逐位填充。
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t length = read_length_prefix(reader, options.max_container_size(), options);
    if (length != N)
    {
        throw std::runtime_error("Bitset length does not match template parameter N");
    }

    const std::size_t bytes_count = (N + 7) / 8;
    std::vector<std::byte> buffer(bytes_count);

    if (!buffer.empty())
    {
        reader.read_bytes(buffer.data(), buffer.size());
    }

    std::bitset<N> result_bits;

    for (std::size_t i = 0; i < N; ++i)
    {
        const std::size_t byte_index = i / 8;
        const unsigned bit_in_byte = static_cast<unsigned>(i % 8);
        const unsigned char byte_value = static_cast<unsigned char>(buffer[byte_index]);
        const bool bit = ((byte_value >> bit_in_byte) & 0x1u) != 0u;
        result_bits.set(i, bit);
    }

    return result_bits;
}

// =============================================================================
// std::forward_list 的默认实现（按长度前缀 + 顺序元素）
// =============================================================================

/**
 * 序列化 std::forward_list
 * 参数:
 *  - writer: 写入器，满足 writer 概念；当满足 seekable_writer 时启用占位长度回填优化
 *  - container: 单向链表容器
 *  - options: 序列化选项（包含最大容器限制、字节序、长度前缀策略）
 * 返回值: 无
 * 异常:
 *  - 当容器大小超过最大限制时抛出 std::runtime_error（在占位回填路径中可能在已写入部分载荷后抛出）
 *  - 可能抛出底层 I/O 异常或子元素序列化异常
 * 说明:
 *  - 当启用 varint 长度或 writer 不支持 seek
 * 时，采取“两次遍历”：先线性统计长度，写入前缀，再逐元素序列化。
 *  - 当 writer 支持 seek 且未启用 varint 长度时，采取“一趟遍历 + 两次写头”：先写入一个固定 64
 * 位整型的占位长度（0），边序列化边统计元素个数，最后回到占位位置写入真实长度，再跳回尾部位置。该路径避免对
 * forward_list 进行两次遍历。
 */
template <typename Writer,
          typename Options,
          typename T,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void

tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::forward_list<T> & container,
           const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    // 循环引用检测（forward_list 本身按地址追踪）
    if (ctx)
    {
        if (ctx->has_circular_reference(&container))
        {
            throw std::runtime_error("Circular reference detected while serializing forward_list");
        }
        ctx->add_reference(&container);
    }

    // 当启用 varint 长度或 writer 不支持 seek 时，保持原有两次遍历路径
    if (use_varint_lengths(options))
    {
        // 统计长度（线性时间）
        std::size_t size = 0;
        for (auto it = container.begin(); it != container.end(); ++it)
        {
            ++size;
        }

        if (size > options.max_container_size())
        {
            if (ctx)
            {
                ctx->remove_reference(&container);
            }
            throw std::runtime_error("Container size exceeds maximum allowed size");
        }

        write_length_prefix(writer, size, options);

        for (const auto & element : container)
        {
            tag_invoke(serialize_tag, writer, element, options);
        }
    }
    else if constexpr (seekable_writer<Writer>)
    {
        // seekable + 固定 64 位长度前缀：写入占位，再一趟遍历记录元素计数，最后回填长度
        const std::size_t prefix_pos = writer.position();
        // 写入 64 位长度占位（按字节序写入 0）
        tag_invoke(serialize_tag, writer, static_cast<std::uint64_t>(0), options);

        std::size_t count = 0;
        for (const auto & element : container)
        {
            tag_invoke(serialize_tag, writer, element, options);
            ++count;
            // 若超过最大限制，仍将长度回填后抛出异常（流已部分写入，符合一般 I/O 异常安全语义）
            if (count > options.max_container_size())
            {
                const std::size_t end_pos = writer.position();
                writer.seek(prefix_pos);
                tag_invoke(serialize_tag, writer, static_cast<std::uint64_t>(count), options);
                writer.seek(end_pos);

                if (ctx)
                {
                    ctx->remove_reference(&container);
                }
                throw std::runtime_error("Container size exceeds maximum allowed size");
            }
        }

        // 正常回填真实长度并恢复到尾部位置
        const std::size_t end_pos = writer.position();
        writer.seek(prefix_pos);
        tag_invoke(serialize_tag, writer, static_cast<std::uint64_t>(count), options);
        writer.seek(end_pos);
    }
    else
    {
        // 非 seekable 写入器：退回到两次遍历路径
        std::size_t size = 0;
        for (auto it = container.begin(); it != container.end(); ++it)
        {
            ++size;
        }

        if (size > options.max_container_size())
        {
            if (ctx)
            {
                ctx->remove_reference(&container);
            }
            throw std::runtime_error("Container size exceeds maximum allowed size");
        }

        write_length_prefix(writer, size, options);

        for (const auto & element : container)
        {
            tag_invoke(serialize_tag, writer, element, options);
        }
    }

    if (ctx)
    {
        ctx->remove_reference(&container);
    }
}

template <typename T,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::forward_list<T>
tag_invoke(deserialize_tag_t<std::forward_list<T>>, Reader & reader, const Options & options)
{
    // 参数: reader 读取器; options 选项
    // 返回值: 反序列化得到的 forward_list<T>
    // 异常: 长度前缀越界/底层 I/O 异常
    // 说明: 按读取的长度依次读取元素，使用 insert_after 维持顺序。
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = read_length_prefix(reader, options.max_container_size(), options);

    std::forward_list<T> result;
    auto before = result.before_begin();

    for (std::size_t i = 0; i < size; ++i)
    {
        T element = tag_invoke(deserialize_tag<T>, reader, options);
        before = result.insert_after(before, std::move(element));
    }

    return result;
}

// ============================================================================
// std::string_view 的默认实现
// ============================================================================

/**
 * std::string_view 的序列化实现
 * 参数:
 *  - writer: 写入器
 *  - value: 要序列化的 string_view
 *  - options: 序列化选项
 * 返回值: 无
 * 异常: 当字符串长度超过最大限制时抛出 std::runtime_error；也可能抛出底层写入异常
 * 说明: string_view 不拥有数据，序列化时将其内容作为字符串处理
 */
template <typename Writer,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void
tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::string_view & value,
           const Options & options)
{
    // 参数: writer 写入器; value 字符串视图; options 序列化选项
    // 返回值: 无
    // 异常: 当字符串长度超过最大限制时抛出 std::runtime_error；也可能抛出底层写入异常
    // 说明: string_view 不拥有数据，按长度前缀 + 原始字节零拷贝输出
    const std::size_t length = value.size();
    if (length > options.max_string_length())
    {
        throw std::runtime_error("String length exceeds maximum allowed size");
    }

    write_length_prefix(writer, length, options);

    if (length > 0)
    {
        const auto * bytes = reinterpret_cast<const std::byte *>(value.data());
        writer.write_bytes(bytes, length);
    }
}

/**
 * std::string_view 的反序列化实现（注意：反序列化为 std::string）
 * 参数:
 *  - reader: 读取器
 *  - options: 序列化选项
 * 返回值: 反序列化得到的 string（不是 string_view，因为 string_view 不拥有数据）
 * 异常: 当字符串长度超过最大限制时抛出 std::runtime_error；也可能抛出底层读取异常
 * 说明: 由于 string_view 不拥有数据，反序列化时返回 std::string
 */
template <typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::string
tag_invoke(deserialize_tag_t<std::string_view>, Reader & reader, const Options & options)
{
    return tag_invoke(deserialize_tag<std::string>, reader, options);
}

// ============================================================================
// long double 的默认实现（受 prefer_decimal_for_long_double 控制）
// ============================================================================

/**
 * long double 的序列化实现（十进制文本 + 长度前缀）
 * 参数:
 *  - writer: 写入器，需满足 writer 概念
 *  - value: 要序列化的 long double 值
 *  - options: 序列化选项，需满足 serialization_options 概念
 * 返回值: 无
 * 异常: 当未开启 prefer_decimal_for_long_double 时抛出 std::runtime_error；
 *       当数值转换失败或字符串长度超过限制时抛出 std::runtime_error；
 *       也可能抛出底层写入异常
 * 说明: 为保证跨平台一致性，开启 prefer_decimal_for_long_double() 后，固定使用
 *       十进制文本表示并写入长度前缀；对非有限值使用 "nan"、"inf"、"-inf" 文本标记。
 */
template <typename Writer,
          typename Options,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void
tag_invoke(serialize_tag_t, Writer & writer, const long double & value, const Options & options)
{
    if (!options.prefer_decimal_for_long_double())
    {
        throw std::runtime_error(
            "Binary serialization for long double is not supported by default. "
            "Enable prefer_decimal_for_long_double() or provide a custom tag_invoke.");
    }

    // 将 long double 转为十进制文本；对非有限值使用固定标记
    std::string text;
    if (std::isfinite(value))
    {
        // 使用最大有效位数，保证可逆解析（round-trip）
        constexpr int precision = std::numeric_limits<long double>::max_digits10;
        // 预留足够空间，避免反复增长
        text.resize(128);
        auto * begin = text.data();
        auto * end = begin + text.size();
        auto result = std::to_chars(begin, end, value, std::chars_format::general, precision);
        if (result.ec != std::errc{})
        {
            throw std::runtime_error("Failed to convert long double to decimal text");
        }
        // 收缩到实际长度
        text.resize(static_cast<std::size_t>(result.ptr - begin));
    }
    else if (std::isnan(value))
    {
        text = "nan";
    }
    else
    {
        text = std::signbit(value) ? "-inf" : "inf";
    }

    const std::size_t length = text.size();
    if (length > options.max_string_length())
    {
        throw std::runtime_error("String length exceeds maximum allowed size");
    }

    write_length_prefix(writer, length, options);
    if (length > 0)
    {
        const auto * bytes = reinterpret_cast<const std::byte *>(text.data());
        writer.write_bytes(bytes, length);
    }
}

/**
 * long double 的反序列化实现（十进制文本 + 长度前缀）
 * 参数:
 *  - reader: 读取器，需满足 reader 概念
 *  - options: 序列化选项，需满足 serialization_options 概念
 * 返回值: 反序列化得到的 long double 值
 * 异常: 当未开启 prefer_decimal_for_long_double 时抛出 std::runtime_error；
 *       当文本解析失败或长度超过限制时抛出 std::runtime_error；
 *       也可能抛出底层读取异常
 * 说明: 为保证跨平台一致性，开启 prefer_decimal_for_long_double() 后，固定读取
 *       十进制文本并解析为 long double；对 "nan"、"inf"、"-inf" 特殊文本做显式处理。
 */
template <typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
long double
tag_invoke(deserialize_tag_t<long double>, Reader & reader, const Options & options)
{
    if (!options.prefer_decimal_for_long_double())
    {
        throw std::runtime_error(
            "Binary deserialization for long double is not supported by default. "
            "Enable prefer_decimal_for_long_double() or provide a custom tag_invoke.");
    }

    const std::size_t length = read_length_prefix(reader, options.max_string_length(), options);
    std::string text;
    if (length > 0)
    {
        text.resize(length);
        auto * bytes = reinterpret_cast<std::byte *>(text.data());
        reader.read_bytes(bytes, length);
    }

    if (text == "nan")
    {
        return std::numeric_limits<long double>::quiet_NaN();
    }
    if (text == "inf")
    {
        return std::numeric_limits<long double>::infinity();
    }
    if (text == "-inf")
    {
        return -std::numeric_limits<long double>::infinity();
    }

    long double value = 0;
    if (!text.empty())
    {
        auto * begin = text.data();
        auto * end = begin + text.size();
        auto result = std::from_chars(begin, end, value, std::chars_format::general);
        if (result.ec != std::errc{} || result.ptr != end)
        {
            throw std::runtime_error("Failed to parse long double from decimal text");
        }
    }

    return value;
}

// ============================================================================
// std::unique_ptr 的默认实现
// ============================================================================

/**
 * std::unique_ptr 的序列化实现
 * 参数:
 *  - writer: 写入器
 *  - ptr: 要序列化的 unique_ptr
 *  - options: 序列化选项
 * 返回值: 无
 * 异常: 由底层序列化逻辑抛出
 * 说明: 先写入是否为空的标志，如果不为空则序列化指向的对象
 */
template <typename Writer,
          typename Options,
          typename T,
          typename Deleter,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void
tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::unique_ptr<T, Deleter> & ptr,
           const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const bool has_value = (ptr != nullptr);
    tag_invoke(serialize_tag, writer, has_value, options);

    if (has_value)
    {
        if (ctx)
        {
            if (ctx->has_circular_reference(ptr.get()))
            {
                throw std::runtime_error(
                    "Circular reference detected while serializing unique_ptr");
            }
            ctx->add_reference(ptr.get());
        }

        tag_invoke(serialize_tag, writer, *ptr, options);

        if (ctx)
        {
            ctx->remove_reference(ptr.get());
        }
    }
}

/**
 * std::unique_ptr 的反序列化实现
 * 参数:
 *  - reader: 读取器
 *  - options: 序列化选项
 * 返回值: 反序列化得到的 unique_ptr
 * 异常: 由底层反序列化逻辑抛出
 * 说明: 先读取是否为空的标志，如果不为空则反序列化对象并创建 unique_ptr
 */
template <typename T,
          typename Deleter,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::unique_ptr<T, Deleter>
tag_invoke(deserialize_tag_t<std::unique_ptr<T, Deleter>>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const bool has_value = tag_invoke(deserialize_tag<bool>, reader, options);

    if (has_value)
    {
        T value = tag_invoke(deserialize_tag<T>, reader, options);
        return std::make_unique<T>(std::move(value));
    }
    else
    {
        return nullptr;
    }
}

// ============================================================================
// std::shared_ptr 的默认实现
// ============================================================================

/**
 * std::shared_ptr 的序列化实现
 * 参数:
 *  - writer: 写入器
 *  - ptr: 要序列化的 shared_ptr
 *  - options: 序列化选项
 * 返回值: 无
 * 异常: 由底层序列化逻辑抛出
 * 说明: 先写入是否为空的标志，如果不为空则序列化指向的对象
 */
template <typename Writer,
          typename Options,
          typename T,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void
tag_invoke(serialize_tag_t,
           Writer & writer,
           const std::shared_ptr<T> & ptr,
           const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const bool has_value = (ptr != nullptr);
    tag_invoke(serialize_tag, writer, has_value, options);

    if (has_value)
    {
        if (ctx)
        {
            if (ctx->has_circular_reference(ptr.get()))
            {
                throw std::runtime_error(
                    "Circular reference detected while serializing shared_ptr");
            }
            ctx->add_reference(ptr.get());
        }

        tag_invoke(serialize_tag, writer, *ptr, options);

        if (ctx)
        {
            ctx->remove_reference(ptr.get());
        }
    }
}

/**
 * std::shared_ptr 的反序列化实现
 * 参数:
 *  - reader: 读取器
 *  - options: 序列化选项
 * 返回值: 反序列化得到的 shared_ptr
 * 异常: 由底层反序列化逻辑抛出
 * 说明: 先读取是否为空的标志，如果不为空则反序列化对象并创建 shared_ptr
 */
template <typename T,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::shared_ptr<T>
tag_invoke(deserialize_tag_t<std::shared_ptr<T>>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const bool has_value = tag_invoke(deserialize_tag<bool>, reader, options);

    if (has_value)
    {
        T value = tag_invoke(deserialize_tag<T>, reader, options);
        return std::make_shared<T>(std::move(value));
    }
    else
    {
        return nullptr;
    }
}

// ============================================================================
// std::valarray 的默认实现
// ============================================================================

/**
 * std::valarray 的序列化实现
 * 参数:
 *  - writer: 写入器
 *  - arr: 要序列化的 valarray
 *  - options: 序列化选项
 * 返回值: 无
 * 异常: 当数组大小超过最大容器限制时抛出 std::runtime_error；也可能抛出底层写入异常
 * 说明: 先写入数组大小，然后逐个序列化元素
 */
template <typename Writer,
          typename Options,
          typename T,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
void
tag_invoke(serialize_tag_t, Writer & writer, const std::valarray<T> & arr, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = arr.size();
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Valarray size exceeds maximum allowed size");
    }

    if (ctx)
    {
        if (ctx->has_circular_reference(&arr))
        {
            throw std::runtime_error("Circular reference detected while serializing valarray");
        }
        ctx->add_reference(&arr);
    }

    write_length_prefix(writer, size, options);

    for (std::size_t i = 0; i < size; ++i)
    {
        tag_invoke(serialize_tag, writer, arr[i], options);
    }

    if (ctx)
    {
        ctx->remove_reference(&arr);
    }
}

/**
 * std::valarray 的反序列化实现
 * 参数:
 *  - reader: 读取器
 *  - options: 序列化选项
 * 返回值: 反序列化得到的 valarray
 * 异常: 当数组大小超过最大容器限制时抛出 std::runtime_error；也可能抛出底层读取异常
 * 说明: 先读取数组大小，然后逐个反序列化元素
 */
template <typename T,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type = 0>
std::valarray<T>
tag_invoke(deserialize_tag_t<std::valarray<T>>, Reader & reader, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = read_length_prefix(reader, options.max_container_size(), options);

    std::valarray<T> result(size);

    for (std::size_t i = 0; i < size; ++i)
    {
        result[i] = tag_invoke(deserialize_tag<T>, reader, options);
    }

    return result;
}

// ============================================================================
// kp::span 的默认实现（支持无 Extent 与带 Extent）
// ============================================================================

/**
 * kp::span 的序列化实现（无 Extent 版本）
 */
template <typename Writer,
          typename Options,
          typename T,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type>
void
tag_invoke(serialize_tag_t, Writer & writer, const kp::span<T> & span_obj, const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = span_obj.size();
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Span size exceeds maximum allowed size");
    }

    if (ctx)
    {
        if (ctx->has_circular_reference(span_obj.data()))
        {
            throw std::runtime_error("Circular reference detected while serializing span");
        }
        ctx->add_reference(span_obj.data());
    }

    write_length_prefix(writer, size, options);

    if (size > 0)
    {
        if constexpr (std::is_same<T, std::byte>::value)
        {
            writer.write_bytes(span_obj.data(), size);
        }
        else if constexpr (portable_arithmetic_type<T>)
        {
            const serializer::byte_order order = options.get_byte_order();
            if (order == serializer::byte_order::native || sizeof(T) == 1)
            {
                const auto * bytes = reinterpret_cast<const std::byte *>(span_obj.data());
                writer.write_bytes(bytes, size * sizeof(T));
            }
            else
            {
                std::vector<std::byte> buffer;
                buffer.resize(size * sizeof(T));

                const T * src = span_obj.data();
                std::byte * dst = buffer.data();

                for (std::size_t i = 0; i < size; ++i)
                {
                    const T converted = convert_byte_order<T>(src[i], order);
                    std::memcpy(dst + i * sizeof(T), &converted, sizeof(T));
                }

                writer.write_bytes(buffer.data(), buffer.size());
            }
        }
        else
        {
            for (const auto & element : span_obj)
            {
                tag_invoke(serialize_tag, writer, element, options);
            }
        }
    }

    if (ctx)
    {
        ctx->remove_reference(span_obj.data());
    }
}

/**
 * kp::span 的反序列化实现（无 Extent 版本，返回 std::vector）
 */
template <typename T,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type>
std::vector<T>
tag_invoke(deserialize_tag_t<kp::span<T>>, Reader & reader, const Options & options)
{
    return tag_invoke(deserialize_tag<std::vector<T>>, reader, options);
}

#ifdef SERIALIZER_HAS_STD_SPAN
/**
 * kp::span 的序列化实现（带 Extent 版本）
 */
template <typename Writer,
          typename Options,
          typename T,
          std::size_t Extent,
          typename std::enable_if<serializer::writer<Writer> &&
                                      serializer::serialization_options<Options>,
                                  int>::type>
void
tag_invoke(serialize_tag_t,
           Writer & writer,
           const kp::span<T, Extent> & span_obj,
           const Options & options)
{
    DefaultContext * ctx = get_current_context();
    RecursionDepthGuard depth_guard(ctx);

    const std::size_t size = span_obj.size();
    if (size > options.max_container_size())
    {
        throw std::runtime_error("Span size exceeds maximum allowed size");
    }

    if (ctx)
    {
        if (ctx->has_circular_reference(span_obj.data()))
        {
            throw std::runtime_error("Circular reference detected while serializing span");
        }
        ctx->add_reference(span_obj.data());
    }

    write_length_prefix(writer, size, options);

    if (size > 0)
    {
        if constexpr (std::is_same<T, std::byte>::value)
        {
            writer.write_bytes(span_obj.data(), size);
        }
        else if constexpr (portable_arithmetic_type<T>)
        {
            const serializer::byte_order order = options.get_byte_order();
            if (order == serializer::byte_order::native || sizeof(T) == 1)
            {
                const auto * bytes = reinterpret_cast<const std::byte *>(span_obj.data());
                writer.write_bytes(bytes, size * sizeof(T));
            }
            else
            {
                std::vector<std::byte> buffer;
                buffer.resize(size * sizeof(T));

                const T * src = span_obj.data();
                std::byte * dst = buffer.data();

                for (std::size_t i = 0; i < size; ++i)
                {
                    const T converted = convert_byte_order<T>(src[i], order);
                    std::memcpy(dst + i * sizeof(T), &converted, sizeof(T));
                }

                writer.write_bytes(buffer.data(), buffer.size());
            }
        }
        else
        {
            for (const auto & element : span_obj)
            {
                tag_invoke(serialize_tag, writer, element, options);
            }
        }
    }

    if (ctx)
    {
        ctx->remove_reference(span_obj.data());
    }
}

/**
 * kp::span 的反序列化实现（带 Extent 版本，返回 std::vector）
 */
template <typename T,
          std::size_t Extent,
          typename Reader,
          typename Options,
          typename std::enable_if<serializer::reader<Reader> &&
                                      serializer::serialization_options<Options>,
                                  int>::type>
std::vector<T>
tag_invoke(deserialize_tag_t<kp::span<T, Extent>>, Reader & reader, const Options & options)
{
    return tag_invoke(deserialize_tag<std::vector<T>>, reader, options);
}
#endif // SERIALIZER_HAS_STD_SPAN

} // namespace serializer